How to Write a Distribution Specification

Introduction

The distributable objects in an Ada program are variables, tasks, subprograms, and packages. A distribution specification, in the form of a separate file from the Ada source program, controls the allocation of such objects onto stations. Since a station is merely a logical processing unit, the user has the freedom to determine the actual mapping from stations onto physical machines (such as the workstations in a cluster or the node processors in a multiprocessor system) at execution time.

A distribution specification consists of two kinds of specifications: zero or more group specifications and at least one station specification. A group specification is a convenient shorthand for grouping Ada objects together so that the objects can be assigned as an inseparable compound object to the same station. A station specification then assigns the Ada objects or groups to a specific station.

The replication specification and EXTENSIBLE directive are provided as optional entries in a distribution specification. They can be used to make the program more efficient and scalable.

Distributable Objects

In an Ada program, the objects that can be distributed are variables, tasks, subprograms, and packages that are declared at the package level. Generic subprograms and packages cannot be distributed, yet their instantiations are distributable.

Home Station Rule

Each of the distributable objects is assigned to its home station using the distribution specification, explicitly or implicitly. Any object within a package has the same home station as the package unless it is explicitly assigned to another station in the specification.

Atomic Objects

A variable, task, or subprogram is considered an atomic object that cannot be subdivided for distribution. For example, neither the elements of an array nor the fields of a record can be scattered across stations (nor can the variables of a task).

Program Library versus Nonprogram Library

There are two types of DADS libraries: program libraries and nonprogram libraries. The library where the main program of an application is linked and built is the program library, while all the other libraries that contain library units to be used by the main program are the nonprogram libraries. For instance, the standard library that contains such packages as TEXT_IO and CALENDAR is a nonprogram library.

There is a difference in the distribution policies of these two types of libraries. The packages in a nonprogram library must be assigned in their entirety to a single station, while different objects within the packages in a program library can be assigned individually to different stations.

Group Specification

A group specification consists of a group header followed by one or more group entries and terminated by a group epilog. The group header is the reserved word GROUP followed by the group name and the reserved word IS. For example:

GROUP group1 IS

A group entry consists of the name of a distributable item followed by a semicolon. The distributable items are as follows:

Library units in a nonprogram library
Library units in a program library
Data objects, subprograms, packages, and tasks visible at the library level and compiled into the current library
The wildcard symbol "*", which represents all units in a nonprogram library that are not specified elsewhere in the distribution specification

The following are examples of group entries:

package1;
package2.mytask;
package2.separate_package.myprocedure;
*;

The group epilog consists of the reserved words END and GROUP followed by a semicolon. For example:

END GROUP;

The following is an example of a group specification:

	GROUP group1 IS
		package1;
		package1.mytask;
		package1.separate_package.myprocedure;
		*;
	END GROUP;

Note that a distributable item can be a enclosed within another distributable item. For example, PACKAGE1.MYTASK is contained within PACKAGE1. It is possible for PACKAGE1 and PACKAGE1.MYTASK to be specified in different groups. In this case, all of PACKAGE1 except MYTASK would end up in one group, and PACKAGE1.MYTASK would be in a different group. The group to which a piece of code is assigned is determined by the innermost enclosing scope specified in a group specification.

Station Specification

A station specification consists of a station header followed by one or more station entries and terminated by a station epilog. The station header is the reserved word STATION followed by the station name and the reserved word IS.

For example:

STATION station1 IS

A station entry consists of the name of a group or the name of a distributable item followed by a semicolon.

The following are examples of station entries:

group1;
package_1;
package_2.mytask;

The station epilog consists of the reserved words END and STATION followed by a semicolon.

For example:

END STATION;

The following is an example of a station specification:

	STATION station1 IS
		group1;
		package_1;
		package_2.mytask;
	END STATION;

Replicate Specification

A replicate specification can be included at the end of the list of station specifications. A replicate specification consists of a replicate header followed by one or more station entries and terminated by the reserved words END REPLICATE. The replicate header consists of the reserved word REPLICATE.

The following is an example of a replicate specification:

	REPLICATE
		group3;
	END REPLICATE;

EXTENSIBLE Directive

The EXTENSIBLE directive can be included at the end of the distribution specification. If the EXTENSIBLE directive is specified, a station independent executable is generated in addition to an executable for each station specified in the distribution specification. If the EXTENSIBLE directive is not used, one executable is produced per station.

Rules Governing the Complete Distribution Specification

A distribution specification consists of zero or more group specifications followed by at least one station specification, subject to the following restrictions:

Each group or station specification has a unique name.
Each distributable object appears at most once in all group and station specifications. The unspecified objects will be distributed with respect to the home station rule if applicable or the rule for wildcard symbol "*".
Subprograms are the only objects that can be replicated.

Specification Grammar

distribution_specification::=
	{group_specification}
	station_specification
	{station_specification}
	[replicate_specification]
	[EXTENSIBLE]

group_specification::=
	GROUP identifier IS
	identifier_or_asterisk;
	{identifier_or_asterisk;}
	END GROUP;
 
identifier_or_asterisk::=
	identifier
      | *
 
station_specification ::=
	STATION identifier IS
	identifier;
	{identifier;}
	END STATION;
 
replicate_specification::=
	REPLICATE
	identifier;
	{identifier;}
	END REPLICATE;

Example of a Dummy Distribution Specification

This is the minimum you need to get started:

STATION DUMMY is
	*;
END STATION;

This allocates the entire program on a single station.

Back to DADS